Chrome 插件开发入门教程

Original 子洋子洋的摘星阁

2024-10-25

1. 介绍

Chrome 插件（也称为扩展程序）是用来扩展和增强 Google Chrome 浏览器功能的小程序。它们允许用户定制和扩展浏览器的功能，为用户提供更丰富、更高效的浏览体验。无论是广告拦截、密码管理、页面翻译，还是开发者工具，Chrome 插件都能满足各种需求。通过创建 Chrome 插件，开发者可以在用户浏览网页时增加额外的功能和体验，提高用户的工作效率和浏览体验。

Manifest V3 (MV3) 是 Chrome 插件的新版本，相较于之前的 Manifest V2 (MV2)，MV3 提供了更高的安全性和性能，同时对隐私保护也做了更严格的规范。MV3 的主要改进包括：

更新 Manifest 配置： manifest.json 版本必须为V3，同时文件格式也发生了改变。
迁移到 Service Worker： Service Worker 替换 V2 中的后台或事件页面，以确保后台代码远离主线程，从而降低性能。此更改还需要将 DOM、窗口和某些扩展 API 调用移入屏幕外的文档中。
更新 API 调用： 某些 API 调用需要替换为更现代的等效项。
替换阻止网络请求监听器： 在 Manifest V2 中屏蔽或修改网络请求可能会显著降低性能，并导致需要过多访问敏感用户数据。借助 Declarative Net Request API，扩展程序可以使用较少的权限来屏蔽或修改 Web 内容，而不会降低性能。
提高扩展程序安全性： Manifest V3 通过多种方式提高扩展程序的安全性。除了增强的内容安全策略之外，不再支持远程托管代码和任意字符串的执行。

本文将详细介绍如何从零开始开发一个简单的 Chrome 插件，包括项目结构、配置文件、脚本编写、加载调试和发布等各个环节。通过学习这个教程，你将掌握 Chrome 插件开发的基础知识，并能创建出符合 MV3 规范的插件。

2. 项目结构

我们首先创建一个基础的项目结构，这将包含开发 Chrome 插件所有必需的文件和目录。

创建项目文件夹

首先，创建一个新的文件夹来存放插件的所有文件，我们将这个文件夹命名为 my-chrome-extension。

mkdir my-chrome-extension
cd my-chrome-extension

项目文件和目录结构

在 my-chrome-extension 文件夹中创建以下文件和目录。这些文件将包含插件的配置、脚本、HTML 和其他资源：

my-chrome-extension/
  ├── manifest.json.  ---------------------- chrome 插件配置文件
  ├── background.js   ---------------------- service work
  ├── content.js      ---------------------- 注入脚本
  ├── popup.html      ---------------------- 插件弹框页面
  ├── popup.js        ---------------------- 插件弹框 js
  └── images/         ---------------------- 插件图标
      ├── icon-16.png
      ├── icon-48.png
      └── icon-128.png

每个文件和文件夹的作用如下：

文件/文件夹名	描述
`manifest.json`	插件的配置文件，包含插件的基本信息、权限和其他元数据。
`background.js`	后台脚本，处理插件的后台逻辑，可以在浏览器后台长时间运行。
`content.js`	内容脚本，可以访问和修改当前网页的 DOM。
`popup.html`	插件弹窗的 HTML 文件，定义了插件插件弹窗的结构和样式。
`popup.js`	处理插件弹窗中的交互逻辑。
`images/`	存放插件的图标文件，包括 16x16、48x48 和 128x128 尺寸的图标。

示例项目结构

以下是项目结构的示例文件内容，帮助你快速入门：

manifest.json

{
  "manifest_version": 3,
  "name": "My Chrome Extension",
  "version": "1.0",
  "description": "一个简单的 Chrome 入门插件示例",
  "action": {
    "default_popup": "popup.html"
  },
  "background": {
    "service_worker": "background.js"
  },
  "permissions": ["activeTab", "scripting"],
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["content.js"]
    }
  ],
  "icons": {
    "16": "images/icon_16.png",
    "32": "images/icon_32.png",
    "48": "images/icon_48.png",
    "128": "images/icon_128.png"
  }
}

background.js

chrome.runtime.onInstalled.addListener(() => {
  console.log('扩展插件已安装');
});

content.js

console.log('已加载内容脚本！');
document.body.style.backgroundColor = 'yellow';

popup.html

<!DOCTYPE html>
<html>
<head>
  <title>Popup</title>
  <style>
    body {
      width: 200px;
      height: 100px;
      font-family: Arial, sans-serif;
    }
  </style>
</head>
<body>
  <h1>Hello, World!</h1>
  <button id="change-color">Change Color</button>
  <script src="popup.js"></script>
</body>
</html>

popup.js

document.getElementById('change-color').addEventListener('click', () => {
  chrome.tabs.query({ active: true, currentWindow: true }, (tabs) => {
    chrome.scripting.executeScript({
      target: { tabId: tabs[0].id },
      function: () => {
        document.body.style.backgroundColor = 'red';
      }
    });
  });
});

3. 配置 `manifest.json`

manifest.json 文件是 Chrome 插件的配置文件，定义了插件的基本信息、权限和各种元数据。它是插件的核心文件，Chrome 浏览器通过这个文件了解插件的功能和结构。下面是如何配置 manifest.json 文件的详细指南。

`manifest.json` 文件解释

以下是示例中 manifest.json 文件配置字段，以及每个字段的解释：

字段名	描述
`manifest_version`	指定 Manifest 版本，MV3 中该值必须为 3。
`name`	插件的名称，将显示在 Chrome 插件管理页面和 Chrome 网上应用店中。
`version`	插件的版本号，使用语义化版本控制（例如：1.0, 1.1.1）。
`description`	插件的描述，解释插件的功能和用途。
`action`	配置插件的图标和弹出页面。 - `default_popup`：定义当用户点击插件图标时显示的 HTML 文件。
`background`	配置后台脚本，使用 `service_worker` 字段指定后台脚本文件。 - `service_worker`：指定后台脚本文件，MV3 中改为使用 Service Worker 而不是 Background Page。
`permissions`	定义插件所需的权限。 - `activeTab`：允许插件访问当前活动标签页的权限。 - `scripting`：允许插件执行`scripting.executeScript()` 方法。
`content_scripts`	定义内容脚本及其注入的页面。 - `matches`：指定内容脚本将注入哪些页面，这里使用 `"<all_urls>"` 表示所有页面。 - `js`：指定内容脚本文件。
`icons`	定义插件的图标文件路径，支持多个尺寸。

更多详细字段介绍，请参阅上一篇文章：Chrome 插件 MV3 配置清单

示例说明

上面的示例配置了一个简单的 Chrome 插件，插件会在安装时打印一条消息，并且包含以下功能：

点击插件图标时会弹出 popup.html 文件中的内容。
后台脚本 background.js 会在插件安装时运行。
内容脚本 content.js 会注入到所有网页中，修改网页背景颜色。
插件需要 activeTab 和 scripting 权限。

确保在 manifest.json 文件中正确配置了所有必要的字段，这样才能使插件能够顺利加载并运行。接下来，我们将介绍一下如何编写后台脚本和内容脚本。

4. 后台脚本 (`background.js`)

后台脚本是 Chrome 插件的核心部分之一，它运行在浏览器的后台，处理长时间运行的任务，如事件监听、消息传递和定时任务。在 Manifest V3 (MV3) 中，后台脚本使用 Service Worker 来代替之前的后台页面，这样可以提高性能和安全性。

后台脚本的作用和功能

后台脚本主要用于以下几种情况：

事件监听：监听和处理各种浏览器事件，如插件安装、标签页更新、消息传递等。
长时间任务：处理需要长时间运行的任务，如周期性检查、数据同步等。
消息传递：与内容脚本和弹出页面进行通信，协调插件的各个部分。

监听插件安装事件

以下是一个简单的后台脚本示例，它会在插件安装时打印一条消息：

// background.js

chrome.runtime.onInstalled.addListener(() => {
  console.log('扩展插件已安装！');
});

在这个示例中，我们使用 chrome.runtime.onInstalled.addListener 方法来监听插件安装事件。当插件首次安装或更新时，会触发此事件，并执行回调函数，在控制台打印一条消息。

高级用法示例

除了基本的安装事件监听，后台脚本还可以处理更多的功能。以下是一些高级用法示例：

1. 监听浏览器动作按钮点击事件

// background.js

chrome.action.onClicked.addListener((tab) => {
  chrome.scripting.executeScript({
    target: { tabId: tab.id },
    function: () => {
      alert('浏览器的操作按钮被点击了！');
    }
  });
});

在这个示例中，我们监听浏览器动作按钮（插件图标）点击事件，并在当前标签页中执行一个脚本，弹出一个提示框。

2. 消息传递

后台脚本可以与内容脚本和弹出页面进行消息传递。以下是一个简单的消息传递示例：

后台脚本

// background.js

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.action === 'getBackgroundInfo') {
    sendResponse({ info: '这是来自 Background 返回的信息' });
  }
});

内容脚本

// content.js

chrome.runtime.sendMessage({ action: 'getBackgroundInfo' }, (response) => {
  console.log(response.info);
});

在这个示例中，内容脚本向后台脚本发送一条消息，请求获取一些信息，后台脚本接收消息后，返回相关信息。

3. 周期性任务

你可以使用 setInterval 在后台脚本中执行周期性任务，例如每分钟执行一次某个操作：

// background.js

setInterval(() => {
  console.log('执行定时任务...');
  // 执行周期性任务的逻辑
}, 60000); // 每分钟执行一次

注意事项

在使用后台脚本时，需要注意以下几点：

生命周期：在 MV3 中，后台脚本使用 Service Worker，具有生命周期限制。Service Worker 只会在需要时启动，并在空闲时终止。因此，不能依赖后台脚本保持长时间运行。
权限管理：确保在 manifest.json 文件中声明所需的权限，以避免权限不足导致的功能无法正常运行。
调试：使用 Chrome 开发者工具调试后台脚本，查看日志和调试信息。

通过利用后台脚本，我们可以实现复杂的插件逻辑和功能。接下来，我们将详细介绍如何编写内容脚本，进一步增强插件的功能。

5. 内容脚本 (`content.js`)

内容脚本是 Chrome 插件的另一个重要组成部分。它们运行在网页的上下文中，可以直接访问和修改网页的 DOM。内容脚本通常用于实现与网页交互的功能，例如高亮显示文本、修改页面内容或收集页面数据。

内容脚本的作用和功能

内容脚本主要用于以下几种情况：

DOM 操作：修改网页内容，增加、删除或修改 DOM 元素。
与后台脚本通信：发送和接收消息，与后台脚本协同工作。
事件监听：监听用户在网页上的操作，如点击、输入等。

修改网页背景颜色

以下是一个简单的内容脚本示例，它会将当前网页的背景颜色修改为黄色：

// content.js

console.log('已加载内容脚本！');
document.body.style.backgroundColor = 'yellow';

这个脚本在加载时会输出一条日志信息，并将当前网页的背景颜色设置为黄色。接下来，我们需要在 manifest.json 文件中配置这个内容脚本。

高级用法示例

除了简单的 DOM 操作，内容脚本还可以执行更多复杂的任务：

1. 与后台脚本通信

内容脚本可以通过消息传递与后台脚本通信，实现复杂的交互逻辑。

在后台脚本示例中有提到，这里就不重复写了。

2. DOM 操作和事件监听

内容脚本可以操作网页 DOM 并监听用户事件：

// content.js

document.body.style.backgroundColor = 'yellow';

const button = document.createElement('button');
button.textContent = 'Click me';
document.body.appendChild(button);

button.addEventListener('click', () => {
  alert('Button clicked!');
});

这个脚本将网页背景颜色设置为黄色，并在页面上添加一个按钮，点击按钮时会弹出提示框。

注意事项

在使用内容脚本时，需要注意以下几点：

隔离性：内容脚本在宿主页面的上下文中运行，但与宿主页面中的 JavaScript 环境是隔离的。你不能直接访问宿主页面的 JavaScript 变量和函数。
权限管理：确保在 manifest.json 文件中正确配置内容脚本的权限和匹配模式。
性能影响：避免在内容脚本中执行耗时的操作，以免影响网页的性能。

通过使用内容脚本，你可以实现与网页的交互，增强插件的用户体验。在接下来的章节中，我们将继续介绍如何创建和管理插件的popup页面。

6. `popup.html` 和 `popup.js`

popup是 Chrome 插件中常见的一部分，通常用于提供用户界面，使用户能够与插件进行交互。当用户点击浏览器工具栏中的插件图标时，插件弹窗会显示出来。

插件弹窗的作用和功能

插件弹窗通常用于以下几种情况：

用户输入：收集用户输入的信息，如表单填写、选项选择等。
展示信息：展示插件运行的结果或状态信息。
触发操作：提供按钮或其他控件，触发插件的功能。

`popup.html`

首先，我们创建一个 popup.html 文件，定义插件弹窗的结构和样式。

<!-- popup.html -->
<!DOCTYPE html>
<html>
<head>
  <title>Popup</title>
  <style>
    body {
      width: 200px;
      height: 100px;
      font-family: Arial, sans-serif;
    }
  </style>
</head>
<body>
  <h1>Hello, World!</h1>
  <button id="change-color">Change Color</button>
  <script src="popup.js"></script>
</body>
</html>

在这个示例中，我们定义了一个简单的 HTML 结构，同时通过 <script> 标签引入 popup.js 文件，这个文件将用来处理插件弹窗的交互逻辑。

`popup.js`

接下来，我们编写 popup.js 文件，处理插件弹窗中的交互逻辑。当用户点击按钮时，我们将改变当前网页的背景颜色。

// popup.js

document.getElementById('change-color').addEventListener('click', () => {
  chrome.tabs.query({ active: true, currentWindow: true }, (tabs) => {
    chrome.scripting.executeScript({
      target: { tabId: tabs[0].id },
      function: () => {
        document.body.style.backgroundColor = 'red';
      }
    });
  });
});

在这个示例中，我们为按钮添加了一个点击事件监听器。当按钮被点击时，代码将执行以下操作：

使用 chrome.tabs.query 获取当前活动的标签页。
使用 chrome.scripting.executeScript 在当前标签页中执行脚本，将网页背景颜色设置为红色。

高级用法示例

插件弹窗可以实现更复杂的功能，如从存储中读取数据、与后台脚本通信等。以下是一些用法示例：

1. 从存储中读取和显示数据

// popup.js

document.addEventListener('DOMContentLoaded', () => {
  chrome.storage.sync.get('color', (data) => {
    if (data.color) {
      document.body.style.backgroundColor = data.color;
    }
  });

  document.getElementById('change-color').addEventListener('click', () => {
    chrome.storage.sync.set({ color: 'red' }, () => {
      document.body.style.backgroundColor = 'red';
    });
  });
});

在这个示例中，插件弹窗加载时会从 Chrome 存储中读取背景颜色，并应用到页面上。点击按钮时，会将背景颜色保存到存储中，并更新页面背景颜色。

2. 与后台脚本通信

// popup.js

document.getElementById('getData').addEventListener('click', () => {
  chrome.runtime.sendMessage({ action: 'getData' }, (response) => {
    alert('从后台接收数据：' + response.data);
  });
});

// background.js

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.action === 'getData') {
    sendResponse({ data: '我是来自 Background 返回的数据' });
  }
});

在这个示例中，插件弹窗发送消息请求数据，后台脚本接收消息并返回数据，然后插件弹窗显示接收到的数据。

注意事项

在开发插件弹窗时，需要注意以下几点：

用户体验：确保插件弹窗的布局和交互逻辑简单明了，提供良好的用户体验。
性能：避免在插件弹窗中执行耗时操作，以免影响用户的交互体验。
安全性：避免在插件弹窗中使用未经验证的用户输入，以防止安全漏洞。

通过合理设计和实现插件弹窗，可以为用户提供直观且便捷的操作界面，增强插件的用户体验。

7. 加载和调试插件

在开发 Chrome 插件时，加载和调试是非常重要的步骤，它们帮助你验证插件的功能并发现潜在的问题。在这一部分，我们将介绍如何在 Chrome 浏览器中加载你的插件，并利用开发者工具进行调试。

加载插件

打开 Chrome 浏览器的扩展程序管理页面

在 Chrome 浏览器中，点击右上角的三点菜单（更多），选择“更多工具” -> “扩展程序”。
或者，直接在地址栏输入 chrome://extensions/ 并按回车键。

启用开发者模式

在扩展程序管理页面的右上角，找到并启用“开发者模式”开关。这将允许你加载未发布的插件和查看详细的调试信息。

加载插件

此时，你的插件将被加载到 Chrome 浏览器中。你应该能在扩展程序管理页面中看到你的插件图标。

点击“加载已解压的扩展程序”按钮。
选择你创建的插件文件夹 my-chrome-extension，然后点击“选择文件夹”。

更新插件

如果你对插件进行了修改，返回到扩展程序管理页面，点击“刷新”按钮（一个箭头的图标）来更新插件。

调试插件

1. 调试后台脚本

在扩展程序管理页面，点击背景页链接（通常显示为Service Worker）以打开开发者工具。这将允许你查看和调试后台脚本的日志、错误和其他信息。
你可以在控制台标签页中查看日志消息，使用断点调试代码。

2. 调试内容脚本

内容脚本运行在网页的上下文中，因此需要打开相应的网页来调试它。
在开发者工具中，切换到源代码标签页，找到内容脚本文件并设置断点。
你可以在控制台标签页中查看内容脚本的日志和错误信息。

3. 调试插件弹窗

点击浏览器工具栏中的插件图标，打开插件弹窗。
在插件弹窗打开的状态下，右键单击插件弹窗并选择检查打开开发者工具。
在开发者工具中，你可以查看和调试插件弹窗的 HTML、CSS 和 JavaScript 文件。

4. 使用 `chrome.runtime.lastError`

在你的插件代码中，你可以使用 chrome.runtime.lastError 来检查 Chrome API 调用中的错误。这对于调试非常有用，例如：

chrome.storage.sync.get('key', (result) => {
  if (chrome.runtime.lastError) {
    console.error('数据获取异常:', chrome.runtime.lastError);
  } else {
    console.log('数据获取结果：', result);
  }
});

这种方法帮助你捕获并处理 API 调用中的错误，以便更好地理解插件的行为。

8. 插件开发常见问题

在开发和发布 Chrome 插件的过程中，会遇到一些常见的问题，我将一些插件开发常见问题简单汇总罗列如下。

1. 插件无法加载

**检查 manifest.json**：确保 manifest.json 文件格式正确，没有语法错误。使用 Chrome 的扩展程序管理页面查看错误日志，检查插件加载过程中是否有错误信息。
文件路径问题：确保所有引用的文件路径在 manifest.json 和代码中都正确无误。

2. 权限问题

权限未授权：确保在 manifest.json 文件中声明了插件所需的所有权限。如果插件的功能未按预期工作，检查是否有缺失的权限。
权限请求过多：避免请求过多的权限，以免引发用户不信任以及一些插件审核问题。使用最小权限原则，只请求实际需要的权限。

3. 内容脚本不注入

matches 配置：检查 manifest.json 文件中的 matches 字段，确保配置了正确的 URL 模式。
脚本文件路径：确保内容脚本文件路径正确，并且文件存在于指定位置。

4. 插件弹窗功能异常

调试：使用 Chrome 开发者工具调试插件弹窗的 JavaScript 代码，查看控制台中的错误信息。
事件处理：确保插件弹窗中的事件处理逻辑正确，避免由于事件未处理或错误处理导致功能异常。

结语

本篇只是基本的 Chrome 插件开发的教程，通过本文可以完成一些简单的插件开发，下一篇文章我将讲解如何搭建一个 Vue3 的 Chrome 插件开发环境。

”FAN某”的离婚财产分割判决书（全文）

”FAN某”的离婚财产分割判决书（全文）

哈里斯女粉搞4B运动、毒杀丈夫，回旋镖能否让美国“血流成河”

这把绝对高端局，只有中国人才懂

许纪霖：珠海驾车撞人事件的背后，弦绷得太紧了，要给人们以松弛感 | 二湘空间

生成图片，分享到微信朋友圈

Chrome 插件开发入门教程

1. 介绍

2. 项目结构

创建项目文件夹

项目文件和目录结构

示例项目结构

3. 配置 manifest.json

manifest.json 文件解释

示例说明

4. 后台脚本 (background.js)

后台脚本的作用和功能

监听插件安装事件

高级用法示例

1. 监听浏览器动作按钮点击事件

2. 消息传递

3. 周期性任务

注意事项

5. 内容脚本 (content.js)

内容脚本的作用和功能

修改网页背景颜色

高级用法示例

1. 与后台脚本通信

2. DOM 操作和事件监听

注意事项

6. popup.html 和 popup.js

插件弹窗的作用和功能

popup.html

popup.js

高级用法示例

1. 从存储中读取和显示数据

2. 与后台脚本通信

注意事项

7. 加载和调试插件

加载插件

调试插件

1. 调试后台脚本

2. 调试内容脚本

3. 调试插件弹窗

4. 使用 chrome.runtime.lastError

8. 插件开发常见问题

1. 插件无法加载

2. 权限问题

3. 内容脚本不注入

4. 插件弹窗功能异常

结语

相关链接

您可能也对以下帖子感兴趣

3. 配置 `manifest.json`

`manifest.json` 文件解释

4. 后台脚本 (`background.js`)

5. 内容脚本 (`content.js`)

6. `popup.html` 和 `popup.js`

`popup.html`

`popup.js`

4. 使用 `chrome.runtime.lastError`